home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / CodeFragments.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  15.9 KB  |  531 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        CodeFragments.h
  3.  
  4.      Contains:    Public Code Fragment Manager Interfaces.
  5.  
  6.      Version:    Technology:    System 7
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1992-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __CODEFRAGMENTS__
  19. #define __CODEFRAGMENTS__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __FILES__
  25. #include <Files.h>
  26. #endif
  27.  
  28.  
  29.  
  30. #if PRAGMA_ONCE
  31. #pragma once
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. #if PRAGMA_IMPORT
  39. #pragma import on
  40. #endif
  41.  
  42. #if PRAGMA_STRUCT_ALIGN
  43.     #pragma options align=mac68k
  44. #elif PRAGMA_STRUCT_PACKPUSH
  45.     #pragma pack(push, 2)
  46. #elif PRAGMA_STRUCT_PACK
  47.     #pragma pack(2)
  48. #endif
  49.  
  50. /*
  51.    §
  52.    ===========================================================================================
  53.    Universal types and constants
  54.    =============================
  55. */
  56.  
  57.  
  58.  
  59. enum {
  60.     kCFragResourceType            = FOUR_CHAR_CODE('cfrg'),
  61.     kCFragResourceID            = 0,
  62.     kCFragLibraryFileType        = FOUR_CHAR_CODE('shlb'),
  63.     kCFragAllFileTypes            = (long)0xFFFFFFFF
  64. };
  65.  
  66.  
  67. typedef OSType                             CFragArchitecture;
  68.  
  69. enum {
  70.     kPowerPCCFragArch            = FOUR_CHAR_CODE('pwpc'),
  71.     kMotorola68KCFragArch        = FOUR_CHAR_CODE('m68k'),
  72.     kAnyCFragArch                = 0x3F3F3F3F
  73. };
  74.  
  75. #if TARGET_CPU_PPC
  76.  
  77. enum {
  78.     kCompiledCFragArch            = kPowerPCCFragArch
  79. };
  80.  
  81. #endif  /* TARGET_CPU_PPC */
  82.  
  83. #if TARGET_CPU_68K
  84.  
  85. enum {
  86.     kCompiledCFragArch            = kMotorola68KCFragArch
  87. };
  88.  
  89. #endif  /* TARGET_CPU_68K */
  90.  
  91. typedef UInt32                             CFragVersionNumber;
  92.  
  93. enum {
  94.     kNullCFragVersion            = 0,
  95.     kWildcardCFragVersion        = (long)0xFFFFFFFF
  96. };
  97.  
  98.  
  99. typedef UInt8                             CFragUsage;
  100.  
  101. enum {
  102.     kImportLibraryCFrag            = 0,                            /* Standard CFM import library.*/
  103.     kApplicationCFrag            = 1,                            /* MacOS application.*/
  104.     kDropInAdditionCFrag        = 2,                            /* Application or library private extension/plug-in*/
  105.     kStubLibraryCFrag            = 3,                            /* Import library used for linking only*/
  106.     kWeakStubLibraryCFrag        = 4                                /* Import library used for linking only and will be automatically weak linked*/
  107. };
  108.  
  109.  
  110.  
  111. enum {
  112.     kIsCompleteCFrag            = 0,                            /* A "base" fragment, not an update.*/
  113.     kFirstCFragUpdate            = 1                                /* The first update, others are numbered 2, 3, ...*/
  114. };
  115.  
  116.  
  117.  
  118. enum {
  119.     kCFragGoesToEOF                = 0
  120. };
  121.  
  122.  
  123.  
  124.  
  125. typedef UInt8                             CFragLocatorKind;
  126.  
  127. enum {
  128.     kMemoryCFragLocator            = 0,                            /* Container is already addressable.*/
  129.     kDataForkCFragLocator        = 1,                            /* Container is in a file's data fork.*/
  130.     kResourceCFragLocator        = 2                                /* Container is in a file's resource fork.*/
  131. };
  132.  
  133.  
  134. /*
  135.    --------------------------------------------------------------------------------------
  136.    A 'cfrg' resource consists of a header followed by a sequence of variable length
  137.    members.  The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
  138.    and for a reasonable display in a debugger.  The actual name field is cut to fit.
  139.    There may be "extensions" after the name, the memberSize field includes them.  The
  140.    general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
  141.    Only one standard extension type is defined at present, it is used by SOM's searching
  142.    mechanism.
  143. */
  144.  
  145.  
  146. union CFragUsage1Union {                                        /* ! Meaning differs depending on value of "usage".*/
  147.     UInt32                             appStackSize;                /* If the fragment is an application. (Not used by CFM!)*/
  148. };
  149. typedef union CFragUsage1Union CFragUsage1Union;
  150.  
  151. union CFragUsage2Union {                                        /* ! Meaning differs depending on value of "usage".*/
  152.     SInt16                             appSubdirID;                /* If the fragment is an application.*/
  153. };
  154. typedef union CFragUsage2Union CFragUsage2Union;
  155.  
  156. union CFragWhere1Union {                                        /* ! Meaning differs depending on value of "where".*/
  157.     UInt32                             spaceID;                    /* If the fragment is in memory.  (Actually an AddressSpaceID.)*/
  158.     OSType                             forkKind;                    /* If the fragment is in an arbitrary byte stream fork.*/
  159. };
  160. typedef union CFragWhere1Union CFragWhere1Union;
  161.  
  162. union CFragWhere2Union {                                        /* ! Meaning differs depending on value of "where".*/
  163.     UInt16                             forkInstance;                /* If the fragment is in an arbitrary byte stream fork.*/
  164. };
  165. typedef union CFragWhere2Union CFragWhere2Union;
  166.  
  167.  
  168. enum {
  169.     kDefaultCFragNameLen        = 16
  170. };
  171.  
  172.  
  173. struct CFragResourceMember {
  174.     CFragArchitecture                 architecture;
  175.     UInt16                             reservedA;                    /* ! Must be zero!*/
  176.     UInt8                             reservedB;                    /* ! Must be zero!*/
  177.     UInt8                             updateLevel;
  178.     CFragVersionNumber                 currentVersion;
  179.     CFragVersionNumber                 oldDefVersion;
  180.     CFragUsage1Union                 uUsage1;
  181.     CFragUsage2Union                 uUsage2;
  182.     CFragUsage                         usage;
  183.     CFragLocatorKind                 where;
  184.     UInt32                             offset;
  185.     UInt32                             length;
  186.     CFragWhere1Union                 uWhere1;
  187.     CFragWhere2Union                 uWhere2;
  188.     UInt16                             extensionCount;                /* The number of extensions beyond the name.*/
  189.     UInt16                             memberSize;                    /* Size in bytes, includes all extensions.*/
  190.     unsigned char                     name[16];                    /* ! Actually a sized PString.*/
  191. };
  192. typedef struct CFragResourceMember CFragResourceMember;
  193.  
  194. typedef CFragResourceMember *            CFragResourceMemberPtr;
  195. struct CFragResourceExtensionHeader {
  196.     UInt16                             extensionKind;
  197.     UInt16                             extensionSize;
  198. };
  199. typedef struct CFragResourceExtensionHeader CFragResourceExtensionHeader;
  200.  
  201. typedef CFragResourceExtensionHeader *    CFragResourceExtensionHeaderPtr;
  202. struct CFragResourceSearchExtension {
  203.     CFragResourceExtensionHeader     header;
  204.     OSType                             libKind;
  205.     unsigned char                     qualifiers[1];                /* ! Actually four PStrings.*/
  206. };
  207. typedef struct CFragResourceSearchExtension CFragResourceSearchExtension;
  208.  
  209. typedef CFragResourceSearchExtension *    CFragResourceSearchExtensionPtr;
  210.  
  211. enum {
  212.     kCFragResourceSearchExtensionKind = 0x30EE
  213. };
  214.  
  215.  
  216. struct CFragResource {
  217.     UInt32                             reservedA;                    /* ! Must be zero!*/
  218.     UInt32                             reservedB;                    /* ! Must be zero!*/
  219.     UInt16                             reservedC;                    /* ! Must be zero!*/
  220.     UInt16                             version;
  221.     UInt32                             reservedD;                    /* ! Must be zero!*/
  222.     UInt32                             reservedE;                    /* ! Must be zero!*/
  223.     UInt32                             reservedF;                    /* ! Must be zero!*/
  224.     UInt32                             reservedG;                    /* ! Must be zero!*/
  225.     UInt16                             reservedH;                    /* ! Must be zero!*/
  226.     UInt16                             memberCount;
  227.     CFragResourceMember             firstMember;
  228. };
  229. typedef struct CFragResource CFragResource;
  230.  
  231. typedef CFragResource *                    CFragResourcePtr;
  232.  
  233. enum {
  234.     kCurrCFragResourceVersion    = 1
  235. };
  236.  
  237.  
  238. #define AlignToFour(aValue)    (((aValue) + 3) & ~3)
  239. #define kBaseCFragResourceMemberSize    (offsetof ( CFragResourceMember, name ) )
  240. #define kBaseCFragResourceSize            (offsetof ( CFragResource, firstMember.name ) )
  241. #define NextCFragResourceMemberPtr(aMemberPtr)    \
  242.         ((CFragResourceMemberPtr) ((BytePtr)aMemberPtr + aMemberPtr->memberSize))
  243. #define FirstCFragResourceExtensionPtr(aMemberPtr)                                            \
  244.         ((CFragResourceExtensionHeaderPtr) ((BytePtr)aMemberPtr +                            \
  245.                                             AlignToFour ( kBaseCFragResourceMemberSize +    \
  246.                                                           aMemberPtr->name[0] + 1 ) ))
  247. #define NextCFragResourceExtensionPtr(anExtensionPtr)                    \
  248.         ((CFragResourceExtensionHeaderPtr) ((BytePtr)anExtensionPtr +    \
  249.                                             ((CFragResourceExtensionHeaderPtr)anExtensionPtr)->extensionSize ))
  250. #define FirstCFragResourceSearchQualifier(searchExtensionPtr)                    \
  251.         ((StringPtr) ((BytePtr)searchExtensionPtr +                                \
  252.                       offsetof ( CFragResourceSearchExtension, qualifiers ) ))
  253. #define NextCFragResourceSearchQualifier(searchQualifierPtr)    \
  254.         ((StringPtr) ((BytePtr)searchQualifierPtr +    searchQualifierPtr[0] + 1))
  255.  
  256. typedef struct OpaqueCFragConnectionID*  CFragConnectionID;
  257. typedef struct OpaqueCFragClosureID*     CFragClosureID;
  258. typedef struct OpaqueCFragContainerID*     CFragContainerID;
  259. typedef struct OpaqueCFragContextID*     CFragContextID;
  260. typedef UInt32                             CFragLoadOptions;
  261.  
  262. enum {
  263.     kReferenceCFrag                = 0x0001,                        /* Try to use existing copy, increment reference counts.*/
  264.     kFindCFrag                    = 0x0002,                        /* Try find an existing copy, do not increment reference counts.*/
  265.     kPrivateCFragCopy            = kReferenceCFrag | 0x0004        /* Prepare a new private copy.*/
  266. };
  267.  
  268.  
  269.  
  270. enum {
  271.     kUnresolvedCFragSymbolAddress = 0
  272. };
  273.  
  274.  
  275. typedef UInt8                             CFragSymbolClass;
  276.  
  277. enum {
  278.     kCodeCFragSymbol            = 0,
  279.     kDataCFragSymbol            = 1,
  280.     kTVectorCFragSymbol            = 2,
  281.     kTOCCFragSymbol                = 3,
  282.     kGlueCFragSymbol            = 4
  283. };
  284.  
  285.  
  286.  
  287. /*
  288.    §
  289.    ===========================================================================================
  290.    System 7 Services 
  291.    ==========================================
  292. */
  293.  
  294.  
  295.  
  296. /*
  297.    ---------------------------------------------------------------------------------
  298.    These declarations are for System 7 and the System 8 cooperative environment, but
  299.    should be avoided under System 8.  Better alternatives exist for System 8.
  300. */
  301.  
  302.  
  303. EXTERN_API( OSErr )
  304. GetSharedLibrary                (ConstStr63Param         libName,
  305.                                  CFragArchitecture         archType,
  306.                                  CFragLoadOptions         loadFlags,
  307.                                  CFragConnectionID *    connID,
  308.                                  Ptr *                    mainAddr,
  309.                                  Str255                 errMessage)                            THREEWORDINLINE(0x3F3C, 0x0001, 0xAA5A);
  310.  
  311. EXTERN_API( OSErr )
  312. GetDiskFragment                    (const FSSpec *            fileSpec,
  313.                                  UInt32                 offset,
  314.                                  UInt32                 length,
  315.                                  ConstStr63Param         fragName,
  316.                                  CFragLoadOptions         loadFlags,
  317.                                  CFragConnectionID *    connID,
  318.                                  Ptr *                    mainAddr,
  319.                                  Str255                 errMessage)                            THREEWORDINLINE(0x3F3C, 0x0002, 0xAA5A);
  320.  
  321. EXTERN_API( OSErr )
  322. GetMemFragment                    (void *                    memAddr,
  323.                                  UInt32                 length,
  324.                                  ConstStr63Param         fragName,
  325.                                  CFragLoadOptions         loadFlags,
  326.                                  CFragConnectionID *    connID,
  327.                                  Ptr *                    mainAddr,
  328.                                  Str255                 errMessage)                            THREEWORDINLINE(0x3F3C, 0x0003, 0xAA5A);
  329.  
  330. EXTERN_API( OSErr )
  331. CloseConnection                    (CFragConnectionID *    connID)                                THREEWORDINLINE(0x3F3C, 0x0004, 0xAA5A);
  332.  
  333. EXTERN_API( OSErr )
  334. FindSymbol                        (CFragConnectionID         connID,
  335.                                  ConstStr255Param         symName,
  336.                                  Ptr *                    symAddr,
  337.                                  CFragSymbolClass *        symClass)                            THREEWORDINLINE(0x3F3C, 0x0005, 0xAA5A);
  338.  
  339. EXTERN_API( OSErr )
  340. CountSymbols                    (CFragConnectionID         connID,
  341.                                  long *                    symCount)                            THREEWORDINLINE(0x3F3C, 0x0006, 0xAA5A);
  342.  
  343. EXTERN_API( OSErr )
  344. GetIndSymbol                    (CFragConnectionID         connID,
  345.                                  long                     symIndex,
  346.                                  Str255                 symName,
  347.                                  Ptr *                    symAddr,
  348.                                  CFragSymbolClass *        symClass)                            THREEWORDINLINE(0x3F3C, 0x0007, 0xAA5A);
  349.  
  350.  
  351. /*
  352.    §
  353.    ===========================================================================================
  354.    Initialization & Termination Routines
  355.    =====================================
  356. */
  357.  
  358.  
  359. /*
  360.    -----------------------------------------------------------------------------------------
  361.    A fragment's initialization and termination routines are called when a new incarnation of
  362.    the fragment is created or destroyed, respectively.  Exactly when this occurs depends on
  363.    what kinds of section sharing the fragment has and how the fragment is prepared.  Import
  364.    libraries have at most one incarnation per process.  Fragments prepared with option
  365.    kPrivateCFragCopy may have many incarnations per process.
  366.    The initialization function is passed a pointer to an initialization information structure
  367.    and returns an OSErr.  If an initialization function returns a non-zero value the entire
  368.    closure of which it is a part fails.  The CFragInitBlock type has different visible parts
  369.    under System 7 and System 8, but is of course the same internally.  The C prototype for an
  370.    initialization function is:
  371.           pascal OSErr    CFragInitFunction    ( const CFragInitBlock *    initBlock );
  372.    The termination procedure takes no parameters and returns nothing.  The C prototype for a
  373.    termination procedure is:
  374.           pascal void        CFragTermProcedure    ( void );
  375. */
  376.  
  377.  
  378. struct CFragSystem7MemoryLocator {
  379.     LogicalAddress                     address;
  380.     UInt32                             length;
  381.     Boolean                         inPlace;
  382.     UInt8                             reservedA;                    /* ! Must be zero!*/
  383.     UInt16                             reservedB;                    /* ! Must be zero!*/
  384. };
  385. typedef struct CFragSystem7MemoryLocator CFragSystem7MemoryLocator;
  386.  
  387. struct CFragSystem7DiskFlatLocator {
  388.     FSSpecPtr                         fileSpec;
  389.     UInt32                             offset;
  390.     UInt32                             length;
  391. };
  392. typedef struct CFragSystem7DiskFlatLocator CFragSystem7DiskFlatLocator;
  393.  
  394. /* ! This must have a file specification at the same offset as a disk flat locator!*/
  395. struct CFragSystem7SegmentedLocator {
  396.     FSSpecPtr                         fileSpec;
  397.     OSType                             rsrcType;
  398.     SInt16                             rsrcID;
  399.     UInt16                             reservedA;                    /* ! Must be zero!*/
  400. };
  401. typedef struct CFragSystem7SegmentedLocator CFragSystem7SegmentedLocator;
  402.  
  403. struct CFragSystem7Locator {
  404.     SInt32                             where;
  405.     union {
  406.         CFragSystem7DiskFlatLocator     onDisk;
  407.         CFragSystem7MemoryLocator         inMem;
  408.         CFragSystem7SegmentedLocator     inSegs;
  409.     }                                 u;
  410. };
  411. typedef struct CFragSystem7Locator CFragSystem7Locator;
  412.  
  413. typedef CFragSystem7Locator *            CFragSystem7LocatorPtr;
  414. struct CFragSystem7InitBlock {
  415.     CFragContextID                     contextID;
  416.     CFragClosureID                     closureID;
  417.     CFragConnectionID                 connectionID;
  418.     CFragSystem7Locator             fragLocator;
  419.     StringPtr                         libName;
  420.     UInt32                             reservedA;                    /* ! Must be zero!*/
  421. };
  422. typedef struct CFragSystem7InitBlock CFragSystem7InitBlock;
  423.  
  424. typedef CFragSystem7InitBlock *            CFragSystem7InitBlockPtr;
  425. typedef CFragSystem7InitBlock             CFragInitBlock;
  426. typedef CFragSystem7InitBlockPtr         CFragInitBlockPtr;
  427. typedef CALLBACK_API_C( OSErr , CFragInitFunction )(const CFragInitBlock *initBlock);
  428. typedef CALLBACK_API_C( void , CFragTermProcedure )(void );
  429. /*
  430.    §
  431.    ===========================================================================================
  432.    Old Name Spellings
  433.    ==================
  434. */
  435.  
  436.  
  437. /*
  438.    -------------------------------------------------------------------------------------------
  439.    We've tried to reduce the risk of name collisions in the future by introducing the phrase
  440.    "CFrag" into constant and type names.  The old names are defined below in terms of the new.
  441. */
  442.  
  443.  
  444.  
  445. enum {
  446.     kLoadCFrag                    = kReferenceCFrag                /* ! Keep kLoadCFrag visible to compilers!*/
  447. };
  448.  
  449.  
  450. #if OLDROUTINENAMES
  451. typedef CFragConnectionID                 ConnectionID;
  452. typedef CFragLoadOptions                 LoadFlags;
  453. typedef CFragSymbolClass                 SymClass;
  454. typedef CFragInitBlock                     InitBlock;
  455. typedef CFragInitBlockPtr                 InitBlockPtr;
  456. typedef CFragSystem7MemoryLocator         MemFragment;
  457. typedef CFragSystem7DiskFlatLocator     DiskFragment;
  458. typedef CFragSystem7SegmentedLocator     SegmentedFragment;
  459. typedef CFragSystem7Locator             FragmentLocator;
  460. typedef CFragSystem7LocatorPtr             FragmentLocatorPtr;
  461. typedef CFragSystem7MemoryLocator         CFragHFSMemoryLocator;
  462. typedef CFragSystem7DiskFlatLocator     CFragHFSDiskFlatLocator;
  463. typedef CFragSystem7SegmentedLocator     CFragHFSSegmentedLocator;
  464. typedef CFragSystem7Locator             CFragHFSLocator;
  465. typedef CFragSystem7LocatorPtr             CFragHFSLocatorPtr;
  466.  
  467. enum {
  468.     kPowerPCArch                = kPowerPCCFragArch,
  469.     kMotorola68KArch            = kMotorola68KCFragArch,
  470.     kAnyArchType                = kAnyCFragArch,
  471.     kNoLibName                    = 0,
  472.     kNoConnectionID                = 0,
  473.     kLoadLib                    = kLoadCFrag,
  474.     kFindLib                    = kFindCFrag,
  475.     kNewCFragCopy                = kPrivateCFragCopy,
  476.     kLoadNewCopy                = kPrivateCFragCopy,
  477.     kUseInPlace                    = 0x80,
  478.     kCodeSym                    = kCodeCFragSymbol,
  479.     kDataSym                    = kDataCFragSymbol,
  480.     kTVectSym                    = kTVectorCFragSymbol,
  481.     kTOCSym                        = kTOCCFragSymbol,
  482.     kGlueSym                    = kGlueCFragSymbol,
  483.     kInMem                        = kMemoryCFragLocator,
  484.     kOnDiskFlat                    = kDataForkCFragLocator,
  485.     kOnDiskSegmented            = kResourceCFragLocator,
  486.     kIsLib                        = kImportLibraryCFrag,
  487.     kIsApp                        = kApplicationCFrag,
  488.     kIsDropIn                    = kDropInAdditionCFrag,
  489.     kFullLib                    = kIsCompleteCFrag,
  490.     kUpdateLib                    = kFirstCFragUpdate,
  491.     kWholeFork                    = kCFragGoesToEOF,
  492.     kCFMRsrcType                = kCFragResourceType,
  493.     kCFMRsrcID                    = kCFragResourceID,
  494.     kSHLBFileType                = kCFragLibraryFileType,
  495.     kUnresolvedSymbolAddress    = kUnresolvedCFragSymbolAddress
  496. };
  497.  
  498.  
  499. enum {
  500.     kPowerPC                    = kPowerPCCFragArch,
  501.     kMotorola68K                = kMotorola68KCFragArch
  502. };
  503.  
  504. #endif  /* OLDROUTINENAMES */
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511. #if PRAGMA_STRUCT_ALIGN
  512.     #pragma options align=reset
  513. #elif PRAGMA_STRUCT_PACKPUSH
  514.     #pragma pack(pop)
  515. #elif PRAGMA_STRUCT_PACK
  516.     #pragma pack()
  517. #endif
  518.  
  519. #ifdef PRAGMA_IMPORT_OFF
  520. #pragma import off
  521. #elif PRAGMA_IMPORT
  522. #pragma import reset
  523. #endif
  524.  
  525. #ifdef __cplusplus
  526. }
  527. #endif
  528.  
  529. #endif /* __CODEFRAGMENTS__ */
  530.  
  531.